<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>generate-mapping: Auto-generating D2RQ mapping files | The D2RQ Platform</title>
    <link rel="stylesheet" type="text/css" href="style.css" />
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
    <script src="script.js"></script>
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-30091096-1']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
  </head>
  <body>
    <header>
      <div class="document-collection">This document is part of the <a href="/">D2RQ documentation</a>.</div>
      <h1><code>generate-mapping</code>: Auto-generating D2RQ mapping files</h1>
    </header>

<p>The <code>generate-mapping</code> tool creates a
<a href="/">D2RQ</a> mapping file by
analyzing the schema of an existing database. This mapping file, called the
<strong>default mapping</strong>, maps each table to a new RDFS class that
is based on the table's name, and maps each column to a property based
on the column's name. This mapping file can be used as-is or can be customized.</p>


<h2 id="usage">Usage</h2>

<pre>generate-mapping <a href="#arg-u">[-u user]</a> <a href="#arg-p">[-p password]</a> <a href="#arg-d">[-d driver]</a>
        <a href="#arg-l">[-l script.sql]</a> <a href="#arg-include-exclude">[--[skip-](schemas|tables|columns) list]</a>
        <a href="#arg-w3c">[--w3c]</a> <a href="#arg-v">[-v]</a> <a href="#arg-b">[-b baseURI]</a> <a href="#arg-o">[-o outfile.ttl]</a>
        <a href="#arg-verbose">[--verbose]</a> <a href="#arg-debug">[--debug]</a>
        <a href="#arg-jdbc-url">jdbcURL</a></pre>


<h3 id="connection">Connection parameters</h3>

<dl>
<dt id="arg-jdbc-url"><code>jdbcURL</code></dt>
<dd><p>JDBC connection URL for the database. Refer to your JDBC driver documentation
for the format for your database engine. Examples:</p>
<p>MySQL: <code>jdbc:mysql://<em>servername</em>/<em>databasename</em></code><br />
PostgreSQL: <code>jdbc:postgresql://<em>servername</em>/<em>databasename</em></code><br />
Oracle: <code>jdbc:oracle:thin:@<em>servername</em>:1521:<em>databasename</em></code><br />
HSQLDB: <code>jdbc:hsqldb:mem:<em>databasename</em></code> (in-memory database)<br />
Microsoft SQL Server: <code>jdbc:sqlserver://<em>servername</em>;databaseName=<em>databasename</em></code> (due to the semicolon, the URL must be put in quotes when passed as a command-line argument in Linux/Unix shells)</p>
<p>If <a href="#arg-l"><code>-l</code></a> is present, then the JDBC URL can be
omitted to load a SQL script into an in-memory HSQLDB database. See
<a href="#example-inmemory">example</a>.</p>
</dd>

<dt id="arg-u"><code>-u user</code></dt>
<dd>The login name of the database user.</dd>

<dt id="arg-p"><code>-p password</code></dt>
<dd>The password of the database user.</dd>

<dt id="arg-d"><code>-d driver</code></dt>
<dd><p>The fully qualified Java class name of the database driver.
For MySQL, PostgreSQL, and HSQLDB, this argument can be omitted as drivers
are already included with D2RQ. For other databases, a driver has to be
downloaded from the vendor or a third party. The jar file containing
the JDBC driver class has to be in D2RQ's <code>/lib/db-drivers/</code>
directory. To find the driver class name,
consult the driver documentation. Examples:</p>
<p>Oracle: <code>oracle.jdbc.OracleDriver</code><br />
Microsoft SQL Server: <code>com.microsoft.sqlserver.jdbc.SQLServerDriver</code></p>
</dd>

<dt id="arg-l"><code>-l script.sql</code></dt>
<dd>Load a SQL script before running the tool. Useful for initializing the connection and testing. The <a href="d2rq-language#d2rq:startupSQLScript"><code>d2rq:startupSQLScript</code></a> property of the database in the generated mapping will be initialized with the same value.</dd>

<dt id="arg-include-exclude"><code>--schemas</code>, <code>--tables</code>, <code>--columns</code>, <code>--skip-schemas</code>, <code>--skip-tables</code>, <code>--skip-columns</code></dt>
<dd><p>Only map the specified schemas, tables or columns.
The value of each argument is a comma-separated list of names.
Schema names are of the form <code>schema</code>,
table names of the form <code>table</code> or </code>schema.table</code>,
and column names are <code>table.column</code> or <code>schema.table.column</code>.</p>

<p>Each dot-separated segment can be specified as a regular expression
encloded between slashes.</p>

<p>If the value starts with “<code>@</code>”, then it is interpreted
as a file name, and the list of names is loaded from the file.
The file contains one name per line or comma-separated names. Examples follow:</p>

<ul>
<li><code>--schema SCOTT</code> (maps only tables in the <code>SCOTT</code> schema)</li>
<li><code>--tables PERSONS,ORGS</code> (maps only the <code>PERSONS</code> and <code>ORGS</code> tables)</li>
<li><code>--skip-table TEMP_CACHE</code> (skips the <code>TEMP_CACHE</code> table)</li>
<li><code>--skip-columns /.*/.CHECKSUM</code> (skips the <code>CHECKSUM</code> column of each table, if present)</li>
<li><code>--skip-tables /BACKUP.*/i</code> (skips tables <code>backup1</code>, <code>BACKUP_2</code> and so on)</li>
<li><code>--skip-tables @exclude.txt</code> (reads a list of excluded table names from a file)</li>
</ul>
</dd>
</dl>


<h3 id="output">Output parameters</h3>

<dl>
<dt id="arg-w3c"><code>--w3c</code></dt>
<dd>Generate a mapping file that is compatible with W3C's <a href="http://www.w3.org/TR/rdb-direct-mapping/">Direct Mapping of Relational Data to RDF</a>. <strong>This is an experimental feature and work in progress.</strong></dd>

<dt id="arg-v"><code>-v</dt></code>
<dd>Generate an RDF Schema description of the vocabulary instead of a mapping file.</dd>

<dt id="arg-o"><code>-o outfile.ttl</code></dt>
<dd>The generated mapping (or vocabulary if <a href="#arg-v"><code>-v</code></a>
is used) will be stored in this file in Turtle syntax. If this
parameter is omitted, the result will be written to standard out.</dd>

<dt id="arg-b"><code>-b baseURI</code></dt>
<dd>The base URI is used to construct a vocabulary namespace that will automatically be served
as Linked Data by D2R Server, following the convention <code>http://<em>baseURI</em>/vocab/resource/</code>.  
This should be the same base URI that is used when invoking the server. Defaults to <code>http://localhost:2020/</code>.
For more information on vocabulary serving, see the <a href="d2rq-language#servingvocabularies">D2RQ language specification</a>.</dd>

<dt id="arg-verbose"><code>--verbose</code></dt>
<dd>Print extra progress log information.</dd>

<dt id="arg-debug"><code>--debug</code></dt>
<dd>Print all debug log information.</dd>
</dl>


<h2 id="examples">Examples</h2>

<h3 id="example-mysql">Local MySQL database</h3>

<pre>generate-mapping -u root jdbc:mysql:///iswc</pre>


<h3 id="example-oracle">Remote Oracle database</h3>

<pre>generate-mapping -u riccyg -p <em>password</em> -d oracle.jdbc.OracleDriver
    -o staffdb-mapping.ttl jdbc:oracle:thin:@ora.intranet.deri.ie:1521:staffdb</pre>

<p>This will save the mapping file into <code>staffdb-mapping.ttl</code>.</p>


<h3 id="example-inmemory">Initializing a temporary in-memory database form a SQL dump</h3>

<pre>generate-mapping -l db_dump.sql -o mapping.ttl</pre>

<p>This will create a new temporary in-memory
  <a href="http://hsqldb.org/">HSQLDB</a> database, load the
  SQL dump <code>db_dump.sql</code> into the database, and
  create a mapping file <code>mapping.ttl</code> for it.
  The mapping file will reference the dump as a
  <a href="d2rq-language#d2rq:startupSQLScript"><code>d2rq:startupSQLScript</code></a>.
  This is a useful setup for quickly testing and debugging D2RQ.</p>


<h3 id="example-exclude">Read a list of excluded columns from a file</h3>

<pre>generate-mapping -u root --skip-columns @bad-columns.txt jdbc:mysql:///iswc</pre>

<p>The file <code>bad-columns.txt</code> would contain column names in
<code>schema.table.column</code> or <code>table.column</code> notation,
one per line.</p>

  </body>
</html>
